<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html
        PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <title></title>
</head>
<body>
    <h2 align="center">Оглавление :</h2>
    1. Структура API.
    2. Описание процесса работы.
    3. Описание основных рабочих классов.
    4. Зависимости в API.
    5. Настройка параметров.
    6. Примеры работы.
    7. Сторонние ресурсы.
    <h1>Структура API</h1>
Приложение имеет структуру пакетов и классов, обеспечивающих работу и настройку. Также присутствуют статические
классы, обеспечивающие пользователь доступ к API, его конфигурацию и другие возможности. Ниже приведена
структура API:

  ReportDesigner - корневой пакет содержит основные интерфейсы и управляющие элементы
  ReportDesigner.configurator - пакет классов отвечающих за конфигуррование проекта
  ReportDesigner.controlModel - пакет классов отвечаюших за контроль построения модели отчета согласно структуре xml документа
  ReportDesigner.converter - пакет классов отвечающих за xsl-fo преобразование отчета в pdf документа
  ReportDesigner.designeXML - пакет классов построения модели отчета согласно структуре xml документа
  ReportDesigner.designePDF - пакет классов построения pdf доумента на основе модели xml документа
  ReportDesigner.reportMap - пакет классов описывающих объектную модель отчета

  <!--Здесь будет вставлена UML модель структуры проекта -->




    <h1>Описание процесса работы</h1>
Возможны два вариантов работы API:
1. конвертирование по средствам xsl-fo преобразования
2. построение pdf документа на основе структурной модели входящего xml файла.

    <h3>1.Конвертирование</h3>
Процесс конвертирования происходит на основе <a href="http://www.w3.org/TR/xsl/"> xsl-fo преобразования </a> и задействует
    <a href="http://xmlgraphics.apache.org/fop/">FOP процессор</a>  входящий в <a href="http://xmlgraphics.apache.org/"> пакет xmlgraphics
    </a> сообщества <a href="http://apache.org/"> Apache.</a>  Пакетом классов отвечающих за конвертирование является
    ReportDesigner.converters. Класс конвертации Convert.java получает на входе параметры входного файла xml.
    Также существует возмоность подключения собственного файла xsl-fo преобразования. С получением фходных элементов
    создается файл конфигурации FOP трасформатора с параметрами шрифтов и других элементтов работы,
    после чего происходит настройка xls трасформатора
    <p>
        TransformerFactory tfactory = TransformerFactory.newInstance();
        Transformer transformer = tfactory.newTransformer(xslSource);
    </p>
    Далее настраивается FOP трансформатор
    <p> // Настройка процессора FOP
        Configuration configuration = dConfigurationBuilder.buildFromFile( new File(
        "D:\\intellij Idea workspase\\renderer\\src\\main\\sources\\userconfig"));
        //подключение FOP ghjwtcjhf
        FopFactory fopFactory = FopFactory.newInstance();
        FOUserAgent foUserAgent = fopFactory.newFOUserAgent();
        foUserAgent.setProducer(this.getClass().getName());
        //установка конфигураии
        fopFactory.setUserConfig(configuration);
        //настройка исполняемых условий
        Fop fop = fopFactory.newFop(MimeConstants.MIME_PDF, foUserAgent);
    </p>
    и само преобразование
    <p>
        // Выполнение преобразования
        Result res = new SAXResult(fop.getDefaultHandler());
        transformer.transform(xmlSource, res);
    </p>
    Как уьверждалось ранее в процессе xsl-fo преобразования используется xsl

    <h3>Создание pdf документа</h3>
 Создание pdf документ выполняется посредсвом пакета  ReportDesigner.designers и класса BuildPDF.java пакета ReportDesigner
    Входные параметры это файл xml и исходящий документ pdf. Класс DesignXML.java создает объектную модель отчета на основе пакета
    ReportDesigner.reportMap. Для анализа используется библиатека SAX и класс EventHandler наследник DefaultHandler библиотеки SAX.
    SAX - это "выталкивающий" API: Вы создаете парсер SAX, и парсер сообщает вам (он выталкивает вам события) о найденных в
    XML-документе элементах. Вот как SAX устраняет недостатки, упомянутые выше: SAX не выстраивает дерево XML-документа в памяти.
    Парсер SAX посылает вам события по мере отыскания элементов в документе XML. Вы сами решаете, как сохранять полученные данные
    (и стоит ли вообще это делать).
    Парсер SAX не создает объекты. У вас есть опция создания объектов, но вы сами, а не парсер, решаете, стоит ли их создавать.
    SAX сразу же начинает посылать вам события. Вам не приходится ждать, пока парсер закончит чтение всего документа.
    События SAX
    SAX API определяет ряд событий. Ваша задача – написать Java-программу, выполняющую что-либо в ответ на все эти события.
    Скорее всего, вы воспользуетесь в своём приложении классами-помощниками SAX. Когда вы используете классы-помощники, вы пишете
    обработчики только для тех событий, которые вас интересуют, а остальную работу выполняет класс-помощник.
    Если вы не обрабатываете событие, парсер его отбрасывает, поэтому вам не придется беспокоиться об использовании памяти,
    о ненужных объектах и прочих проблемах. Помните, что события SAX не сохраняют состояние (stateless). Другими словами, вы не
    сможете взглянуть на отдельное событие SAX и определить его контекст. Если вам необходимо знать, что определённый фрагмент текста
    встретился внутри элемента (report), который находится внутри элемента (rtable), вам самим придётся следить, какие элементы парсер
    уже нашёл до этого. Всё, что вам скажет событие SAX: "Здесь какой-то текст". И это ваша работа определить, к какому элементу относится
    этот текст.
    Он выполняет последовательный аналез xml документа и вызывает следующие события
    <p>
        В приложении XML, основанном на SAX, вы потратите основную часть времени, следя за пятью основными событиями.
        Я расскажу о них здесь, а чуть позже рассмотрю события, связанные с обработкой ошибок.
        startDocument()
        Сообщает вам, что парсер нашел начало документа. Это событие не передаёт вам никакой информации, оно просто даёт вам знать,
        что парсер собирается начать сканировать документ.
        endDocument()
        Информирует вас о том, что парсер нашел конец документа.
        startElement(...)
        Информирует вас о том, что парсер нашел тег начала. Это событие сообщает вам имя элемента, имена и значения всех
        атрибутов элемента, а также даёт некоторую информацию о пространстве имен.
        characters(...)
        Информирует вас о том, что парсер нашел текст. Вы получаете символьный массив вместе со значением смещения в
        этом массиве и переменную длины; вместе взятые эти три переменные дают вам текст, найденный парсером.
        endElement(...)
        Информирует вас о том, что парсер нашел тег конца. Это событие сообщает вам имя элемента, а также связанную с
        ним информацию о пространстве имен.
        startElement(), characters() и endElement() - наиболее важные события; далее я подробнее расскажу о них.
        (startDocument и endDocument и информируют вас только о начале и окончании анализа.) Все эти события являются
        частью интерфейса ContentHandler; другие интерфейсы SAX предназначены для обработки ошибок, а также объектов и других
        редко встречающихся вещей.
    </p>
    Подробнее <a href="http://www.ibm.com/developerworks/ru/edu/xmljava/section4.html">Пример парсера xml  документа</a>
    Сначала мы начинаем выполнение сканарования xml документа. Затем производится постраение объектной модели и на основе нее создание
    pdf документа классом DesignPDF. Заголовок и "подвал" страницы pdf документа формируется за счет класса HeaderFooter.java наследника
    класса PdfPageEventHelper.java пакета com.itextpdf.text.pdf.



    <h1>Описание основных рабочих классов</h1>

    <h1>Зависимости в API</h1>

    <h1>НАстройка параметров</h1>

    <h1>Примеры работы</h1>

    <h1>Сторонние ресурсы</h1>
<a href="http://xmlgraphics.apache.org/fop/"> Apache FOP </a>,
<a href="http://www.w3.org/TR/xsl/">xsl-fo</a>
<a href="http://itextpdf.com/"> itextpdf  </a>

</body>
</html>